feat(mcp): add no-OAuth docs-only endpoint at ?category=docs#230
Merged
Conversation
Strict docs-only mode (?category=docs with no other category and no projectId) bypasses withMcpAuth entirely so the documentation tools (list_docs_resources, get_doc_resource) can be embedded anonymously without an OAuth flow. These handlers only fetch from neon.com and never touch the Neon API client, so anonymous access is safe. Any other category combination, or the presence of a projectId, keeps today's authenticated flow.
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
|
🚀 Deployed to https://preview-mcp.neon.tech This PR now owns the preview environment. OAuth flow is available for testing. |
Keep anonymous docs mode independent from the authenticated tool handler map by sharing small docs fetch helpers and registering the two docs callbacks directly.
3 tasks
The docs-only endpoint is fully anonymous; an unauthenticated caller that triggers a stalled neon.com fetch could otherwise hold a Vercel concurrency slot for the full 800s function duration. Add AbortSignal.timeout(10_000) to both fetch calls in handlers/docs.ts. Update existing fetch-call assertions to accept the new signal arg. Co-authored-by: Isaac
CLAUDE.md forbids third-party uptime as a merge-gating CI dependency. The tools/call list_docs_resources case exercised a real fetch through to neon.com via the dev server; Playwright's request.route() cannot intercept server-side fetches, so the test is skipped with a comment describing the dev-server-level stub needed to restore it. Co-authored-by: Isaac
The ?category=docs branch in handleRequest is the entire OAuth-bypass surface but only had Playwright e2e coverage. A regression that swaps the predicate or routes docs-only requests through authHandler would not fail merge-gating CI. Add an integration case that POSTs /api/mcp?category=docs without an Authorization header and asserts status<300, no WWW-Authenticate header, and that model.getAccessToken is never consulted. Co-authored-by: Isaac
Missed in f530ffa: mcp-server.e2e.test.ts also asserts that fetch is called with a single argument, which now includes the AbortSignal added to handlers/docs.ts. Co-authored-by: Isaac
pffigueiredo
approved these changes
May 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
?category=docswith no other category and noprojectId) that bypasses OAuth entirely on/api/mcpand/api/sse, exposing onlylist_docs_resourcesandget_doc_resource.mcp.neon.tech/mcp?category=docs) with no account, no OAuth flow, and noWWW-Authenticate401 challenge.projectId, keeps the existing authenticated flow unchanged.Why it's safe
The two docs handlers (
landing/mcp-src/tools/tools.ts) only callfetch(NEON_DOCS_INDEX_URL)/fetch(\${NEON_DOCS_BASE_URL}/${slug}`)and never touchneonClientorextra.account.validateDocSlug` already blocks path traversal and absolute URLs.Implementation
isDocsOnlyRequest(params)helper inlanding/mcp-src/utils/grant-context.ts.createDocsOnlyMcpHandler()inlanding/app/api/[transport]/route.ts. It builds amcp-handlerinstance withoutwithMcpAuth, registers only docs-scoped tools, and overridestools/listto surface only that subset. Telemetry uses a fixedanonymous-docsanonymousId.handleRequestbranches to the lazily-initialized docs-only handler before falling through toauthHandler.getAvailableTools/grant-filterfor docs-only so the always-availablesearch/fetchtools (which need API auth) are not surfaced anonymously.Test plan
pnpm run lintpnpm run typecheckpnpm run fmt:checkpnpm run knippnpm run test:unit(135/135 pass, includes 9 new cases forisDocsOnlyRequest)pnpm run test:e2e:web(22/22 pass, includes 5 new cases ine2e/docs-only-mcp.spec.tscovering: initialize without auth,tools/listreturns only docs tools,tools/call list_docs_resourcessucceeds, mixed categories still 401, andcategory=docs+projectIdstill 401)curl -X POST 'https://preview-mcp.neon.tech/mcp?category=docs' -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"smoke\",\"version\":\"1.0.0\"}}}'→ expect 200 with noWWW-Authenticateheader.?category=docsstill returns 401 with OAuth challenge.Risk / follow-ups
neon.com. If abuse is a concern, add a per-IP rate limit (out of scope here)./.well-known/oauth-protected-resourcekeeps advertising OAuth; clients only act on it after a 401, which we no longer return for docs-only requests, so this is a no-op for them.